
\chapter{Import/Export From Other Formats}
\label{cha:pgfplots:importexport}

{
\tikzset{external/figure name/.add={}{importexport_}}

This chapter contains information of how to single pictures into separate
\pdf{} graphics files (or \eps{} graphics files). Furthermore, it explains a
Matlab$^\text{\textregistered}$ script which allows to convert from Matlab to
\PGFPlots{}.


\section[Export to PDF/EPS]{Export to {\normalfont\pdf{}/\eps{}}}
\label{sec:pgfplots:export}

It is possible to export images to single \pdf{}-documents using routines of
\pgfname{} and/or \Tikz{}.


\subsection{Using the Automatic Externalization Framework of \Tikz}

\begin{pgfplotslibrary}{external}
\pgfkeys{/pdflinks/search key prefixes in/.add={/tikz/external/,}{}}
    The |external| library offers a convenient method to export every single
    |tikzpicture| into a separate~|.pdf| (or~|.eps|). Later runs of \LaTeX{}
    will simply include these graphics, thereby reducing typesetting time
    considerably.

    The library can also be used to submit documents to authors who do not even
    have \PGFPlots{} or \Tikz{} installed.


    \paragraph{Technical foreword:}

    The |external| library has been written by Christian Feuersänger (author
    of \PGFPlots). It has been contributed to \Tikz{} as general purpose
    library, so the reference documentation along with all tweaks can be found
    in~\cite[Section ``Externalization Library'']{tikz}. The command
    |\usepgfplotslibrary{external}| is actually just a wrapper which loads
    |\usetikzlibrary{external}| or, if this library does not yet exist because
    the installed \pgfname{} has at most version $2.00$, it will load a copy
    which is shipped with \PGFPlots{}.

    The |external| library has been designed such that \emph{no changes} to the
    document as such are necessary. The idea is as follows:
    %
    \begin{enumerate}
        \item Every |\begin{tikzpicture}| $\dotsc$ |\end{tikzpicture}| gets a
            file name. The file name can be assigned manually with
            |\tikzsetnextfilename|\marg{output file name} or automatically,
            in which case \meta{tex file name}|-figure|\meta{number} is used
            with an increasing \meta{number}.

        \item The library writes the resulting images using system calls of
            the form |pdflatex --jobname |\meta{output file name}
            automatically, using the write18 system call of \TeX{}. It is the
            same framework which can be used to call |gnuplot|.
    \end{enumerate}
    %
    The only steps which are necessary is to use

    \pgfmanualpdflabel{\textbackslash tikzexternalize}{}%
    |\usepgfplotslibrary{external}|

    |\tikzexternalize|

    \noindent somewhere in your document's preamble (see below for
    system-dependent configuration options). No further modification to the
    document is necessary. Suppose we have a file called |test.tex|:
    %
\begin{codeexample}[code only]
\documentclass{article}
\usepackage{pgfplots}
    \usepgfplotslibrary{external}
    \tikzexternalize% activate externalization!
\begin{document}
    \begin{figure}
        \begin{tikzpicture}
            \begin{axis}
                \addplot {x^2};
            \end{axis}
        \end{tikzpicture}
        \caption{Our first external graphics example}
    \end{figure}

    \begin{figure}
        \begin{tikzpicture}
            \begin{axis}
                \addplot {x^3};
            \end{axis}
        \end{tikzpicture}
        \caption{A second graphics}
    \end{figure}
\end{document}
\end{codeexample}
    %
    \noindent To enable the system calls, we type
    %
\begin{codeexample}[code only]
pdflatex -shell-escape test
\end{codeexample}
    %
    \noindent and \LaTeX{} will now generate the required graphics files
    |test-figure0.pdf| and |test-figure1.pdf| automatically. Any further call
    to |pdflatex| will simply use |\includegraphics| and the |tikzpicture|s as
    such are no longer considered (you need a different command line switch for
    MiK\TeX{}, see the |shell escape| option).

    If a figure shall be remade, one can simply delete all or selected graphics
    files and regenerate them. Alternatively, one can use the command
    |\tikzset{external/force remake}| somewhere in the document to remake every
    following picture automatically.

    There are three ways to modify the file names of externalized figures:
    %
    \begin{itemize}
        \item Changing the overall file name using a |prefix|,
        \item Changing the file name for a single figure using
            |\tikzsetnextfilename|,
        \item Changing the file name for a restricted set of figures using
            |figure name|.
    \end{itemize}

    \begin{key}{/tikz/external/prefix=\marg{file name prefix} (initially empty)}
        A shortcut for |\tikzsetexternalprefix|\marg{file name prefix}, see
        below.
    \end{key}

    \begin{command}{\tikzsetexternalprefix\marg{file name prefix}}
        Assigns a common prefix used by all file names. For example,
        %
\begin{codeexample}[code only]
\tikzsetexternalprefix{figures/}
\end{codeexample}
        %
        will prepend |figures/| to every external graphics file name.
    \end{command}

    \begin{command}{\tikzsetnextfilename\marg{file name}}
        Sets the file name for the \emph{next} \tikzname{} picture or |\tikz|
        short command. It will \emph{only} be used for the next picture.

        Pictures for which no explicit file name has been set will get
        automatically generated file names.

        Please note that |prefix| will still be prepended to \meta{file name}.
        %
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}
    \usepgfplotslibrary{external}
    \tikzexternalize[prefix=figures/]% activate with a name prefix
\begin{document}
\tikzsetnextfilename{firstplot}
\begin{tikzpicture} % will be written to 'figures/firstplot.pdf'
    \begin{axis}
        \addplot {x};
    \end{axis}
\end{tikzpicture}

\begin{tikzpicture} % will be written to 'figures/main-figure0.pdf'
   \draw [help lines] (0,0) grid (5,5);
\end{tikzpicture}
\end{document}
\end{codeexample}

\begin{codeexample}[code only]
pdflatex -shell-escape main
\end{codeexample}
        %
    \end{command}

    \begin{key}{/tikz/external/figure name=\marg{name}}
        Same as |\tikzsetfigurename|\marg{name}.
    \end{key}

    \begin{command}{\tikzsetfigurename\marg{name}}
        Changes the names of \emph{all} following figures. It is possible to
        change |figure name| during the document using
        |\tikzset{external/figure name|=\marg{name}|}|. A unique counter will
        be used for each different \meta{name}, and each counter will start at
        $0$.\footnote{These counters are stored into different \emph{macros}.
        In other words: no \TeX{} register will be needed.}

        The value of |prefix| will be applied after |figure name| has been
        evaluated.
        %
\begin{codeexample}[code only]
\documentclass{article}
% main document, called main.tex
\usepackage{tikz}
    \usepgfplotslibrary{external}
    \tikzexternalize% activate externalization!
\begin{document}
% will be written to 'main-figure0.pdf'
\begin{tikzpicture}
    \begin{semilogyaxis}
        \addplot {exp(x)};
    \end{semilogyaxis}
\end{tikzpicture}

{
    \tikzset{external/figure name={subset_}}
    A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf'

    \begin{tikzpicture} % will be written to 'subset_1.pdf'
        \begin{axis}
            \addplot {x^2};
        \end{axis}
    \end{tikzpicture}
}% here, the old file name will be restored:

\begin{tikzpicture} % will be written to 'main-figure1.pdf'
    \begin{axis}
        \addplot[domain=1e-3:100] {1/x};
    \end{axis}
\end{tikzpicture}
\end{document}
\end{codeexample}
        %
        The scope of |figure name| ends with the next closing brace (as all values set by |\tikzset| do).

            \medbreak
        Remark: Use
        |\tikzset{external/figure name/.add=|\marg{prefix}\marg{suffix}|}| to
        prepend a \meta{prefix} and append a \meta{suffix} to the actual value
        of |figure name|. Might be useful for something like
        %
\begin{codeexample}[code only]
\tikzset{external/figure name=main}

% uses main_0.pdf, main_1.pdf, ...

\chapter{The first section}
{\tikzset{external/figure name/.add={}{_firstsection}}
    ...
    % uses main_firstsection_0.pdf, main_firstsection_1.pdf, ...
}

\chapter{The second section}
{\tikzset{external/figure name/.add={}{secondsection_}}
    ...
    % uses main_secondsection_0.pdf, main_secondsection_1.pdf, ...
    \section{Second subsection}
    {\tikzset{external/figure name/.add={}{sub_}}
        ...
        % uses main_secondsection_sub_0.pdf, main_secondsection_sub_1.pdf, ...
    }
    % uses main_secondsection_2.pdf, main_secondsection_3.pdf, ...
}
\end{codeexample}
    \end{command}

    \begin{command}{\tikzappendtofigurename\marg{suffix}}
        Appends \meta{suffix} to the actual value of |figure name|.

        It is a shortcut for
        |\tikzset{external/figure name/.add={}|\marg{suffix}|}| (a shortcut
        which is also supported if \tikzname{} is not installed, see below).
    \end{command}


    \paragraph{Configuration option for \textsc{eps} output or MiK\TeX{}:}

    Since the |external| lib works by means of system calls, it has to be
    modified to fit the local system. This is necessary for MiK\TeX{} since it
    uses a different option to enable these system calls. It is also necessary
    for \textsc{eps} output since this involves a different set of utilities.

    Note that the \emph{most important part} is to enable system calls. This is
    typically done by typesetting your document with |pdflatex -shell-escape|
    or |pdflatex -enable-write18| (MiK\TeX{}). These options \emph{need to be
    configured in your \TeX{} editor}. Besides this step, one may want to
    configure the system call:

    \begin{key}{/tikz/external/system call=\marg{template}}
    \label{extlib:systemcall:option}
        A template string used to generate system calls. Inside of
        \meta{template}, the macro |\image| can be used as placeholder for the
        image which is about to be generated while |\texsource| contains the
        main file name (in truth, it contains |\input|\marg{main file name},
        but that doesn't matter).

        The default is
        %
\begin{codeexample}[code only]
\tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error
    -interaction=batchmode -jobname "\image" "\texsource"}
\end{codeexample}
        %
        \noindent where \declareandlabel{\tikzexternalcheckshellescape} inserts
        the value of the configuration key |shell escape| if and only if the
        current document has been typeset with |-shell-escape|.\footnote{Note
        that this is always true for the default configuration. This security
        consideration applies mainly for \texttt{mode=list and make} which will
        also work \emph{without} shell escapes.}

        For |eps| output, you can (and need to) use
        %
\begin{codeexample}[code only]
\tikzset{external/system call={latex \tikzexternalcheckshellescape -halt-on-error
    -interaction=batchmode -jobname "\image" "\texsource" &&
    dvips -o "\image".ps "\image".dvi}}
\end{codeexample}

        The argument \meta{template} will be expanded using |\edef|, so any
        control sequences will be expanded. During this evaluation, `|\\|' will
        result in a normal backslash, `|\|'. Furthermore, double quotes `|"|',
        single quotes `|'|', semicolons and dashes `|-|' will be made to normal
        characters if any package uses them as macros. This ensures
        compatibility with the |german| package, for example.
    \end{key}

    \begin{key}{/tikz/external/shell escape=\marg{command-line arg} (initially -shell-escape)}
        Contains the command line option for |latex| which enables the
        |\write18| feature.

        For \TeX{}Live, this is |-shell-escape|. For MiK\TeX{}, the system uses |-enable-write18|.
    \end{key}


    \paragraph{Support for Labels and References In External Files}

    The |external| library comes with extra support for |\label| and |\ref|
    (and other commands which usually store information in the |.aux| file)
    inside of external files.

    There are, however, some points which need your attention when you try to
    use
    %
    \begin{enumerate}
        \item[a)] |\ref| to something in the main document inside of an
            externalized graphics or
        \item[b)] |\label| in the externalized graphics which is referenced
            in the main document.
    \end{enumerate}

    For point a), a |\ref| inside of an externalized graphics works \emph{only}
    if you issue the required system call \emph{manually} or by |make|. The
    initial configuration |mode=convert with system call| does \emph{not}
    support |\ref|. But you can copy--paste the system call generated by
    |mode=convert with system call| and issue it manually. The reason is that
    |\ref| information is stored in the main |.aux| file -- but this auxiliary
    file is not completely written when |mode=convert with system call| is
    invoked (there is a race condition). Note that |\pageref| is not supported
    (sorry). Thus: if you have |\ref| inside of external graphics, consider
    using |mode=list and make| or copy--paste the system call for the image(s)
    and issue it manually.

    Point b) is realized automatically by the external library. In detail, a
    |\label| inside of an externalized graphics causes the external library to
    generate separate auxiliary files for every external image. These files are
    called \meta{imagename}|.dpth|. The extension |.dpth| indicates that the
    file also contains the image's depth (the |baseline| key of \tikzname).
    Furthermore, anything which would have been written to an |.aux| file will
    be redirected to the |.dpth| file -- but only things which occur inside of
    the externalized |tikzpicture| environment. When the main document loads
    the image, it will copy the |.dpth| file into the main |.aux| file. Then,
    successive compilations of the main document contain the external |\label|
    information. In other words, a |\label| in an external graphics needs the
    following work flow:
    %
    \begin{enumerate}
        \item The external graphics needs to be generated together with its
            |.dpth| (usually automatically by \tikzname).
        \item The main document includes the external graphics and copies the
            |.dpth| content into its main |.aux| file.
        \item The main document needs to be translated once again to re-read
            its |.aux| file.\footnote{Note that it is not possible to
            activate the content of an auxiliary file after
            \texttt{\textbackslash begin\{document\}} in \LaTeX{}.}
    \end{enumerate}
    %
    There is just a special case if a |\label|/|\ref| drawn as a |tikzpicture|.
    This is, for example, the case for the legend |\ref| images or for the
    |\pgfplotslegendfromname| feature. In such cases, you need to proceed as
    for case a) since |mode=convert with system call| can't handle that stuff
    on its own.

    In other words: a |\label| in an external document works automatically,
    just translate the main document often enough. A |\ref| might need manual
    adjustments as described for case a) above.


    \paragraph{Operation Modes}

    \begin{key}{/tikz/external/mode=\mchoice{convert with system call,list and make,$\dotsc$} (initially convert with system call)}
        This allows to change the default operation mode. There are a handful
        of choices possible, all of them are described in detail
        in~\cite[Section ``Externalization Library'']{tikz}. The most useful
        ones are probably the initial configuration |convert with system call|
        and the specialized choice |list and make|.

        The choice |list and make| configures the library to check if there are
        already external graphics and uses them. If there are no graphics, the
        library will \emph{skip} the figure. However, it will also generate a
        |makefile| to generate the graphics, and a list of all required
        graphics files.

        It is not required to use |make|: the library expects you to generate
        the images somehow and it doesn't care about the ``how''. Using
        |make -f |\meta{name-of-tex-file}|.makefile -j 2| allows parallel
        execution which might, indeed, be an option. Furthermore, the makefile
        also supports file dependencies: if one of your data tables has been
        updated, the external graphics will be remade automatically.
        \PGFPlots{} tells the external library about any file dependencies
        (input files and tables).

        The two modes have the following characteristics:
        %
        \begin{enumerate}
            \item |convert with system call| is automatic and does everything
                on the fly. However, it \emph{can't} work with |\ref| and/or
                |\label| information in external pictures.
            \item |list and make| requires either manual (by issuing the
                system calls manually) or semiautomatic conversion (using the
                generated \meta{main}|.makefile|), and multiple runs of
                |pdflatex|. The generated Makefile can be processed in
                parallel. Furthermore, |list and make| provides \emph{full
                support} for |\ref| and |\label|: any |\label| defined inside
                of an externalized graphics is still available for the main
                document.

                If you have legends with |legend to name| or |\label|/|\ref|,
                you need to generate the graphics defining the |\label| (or
                |legend to name|), then run |pdflatex| twice on the main
                document. Afterwards, you can externalize the legend graphics.
        \end{enumerate}
    \end{key}

    The complete reference documentation and remaining options are documented
    in~\cite[``Externalization Library'']{tikz}. This reference also contains
    information about
    %
    \begin{itemize}
        \item how to use
            |\tikzset{external/|\declareandlabel{force remake}|}| and
            |\tikzset{external/|\declareandlabel{remake next}|}| to remake
            selected figures,
        \item how to disable the externalization partially with
            |\tikzset{external/|\declareandlabel{export}|=false}| or
            completely with |\tikzexternaldisable|,
        \item how to optimize the speed of the conversion process using
            |\tikzset{external/optimize command away=\myExpensiveMacro}|,
        \item how to add further remake-dependencies with
            |\tikzpicturedependsonfile|\marg{name} and/or
            |\tikzexternalfiledependsonfile|\marg{external file}\marg{name},
        \item examples how to enable |png| export,
        \item how to typeset such a document without \pgfname{} installed or
        \item how to provide workarounds with |.pdf| images and bounding box
            restrictions. \index{External Graphics!Bounding Box Issues}
            \index{Bounding Box Control!Image Externalization Problems}
    \end{itemize}


    \paragraph{Using the Library Without {\normalfont\pgfname} or {\normalfont\PGFPlots} Installed}

    There is a small replacement package \declareandlabel{tikzexternal.sty}
    which can be used once every figure has been exported. The idea is to
    comment |\usepackage{tikz}| and |\usepackage{pgfplots}| and write
    |\usepackage{tikzexternal}| instead:
    %
\begin{codeexample}[code only]
% \usepackage{tikz}
% \usepackage{pgfplots}
\usepackage{tikzexternal}
    \tikzexternalize% activate externalization
\begin{document}
    \begin{tikzpicture}
        ...
    \end{tikzpicture}
...
\end{document}
\end{codeexample}
    %
    You do not need \pgfname{}, \tikzname{} or \PGFPlots{} installed. What you
    need is |tikzexternal.sty| and all generated figures (consisting of the
    image files, `|.pdf|' and the `|.dpth|' files containing information of the
    |baseline| option). The file |tikzexternal.sty| is shipped with \pgfname{}
    in the directory
    %
\begin{codeexample}[code only]
latex/pgf/utilities/tikzexternal.sty
\end{codeexample}
    %
    and a copy is shipped with \PGFPlots{} in
    %
\begin{codeexample}[code only]
tex/generic/pgfplots/oldpgfcompatib/pgfplotsoldpgfsupp_tikzexternal.sty
\end{codeexample}
    %
    Just copy the file into your directory and rename it to |tikzexternal.sty|.


    \paragraph{Attention:}

    The small replacement package doesn't support key--value interfaces. Thus,
    it is necessary to use |\tikzsetexternalprefix| instead of the |prefix|
    option and |\tikzsetfigurename| instead of the |figure name| option since
    |\tikzset| is not available in such a context. Also, you may want to define
    a dummy macro |\pgfplotsset| if you have used |\pgfplotsset|.
\end{pgfplotslibrary}


\subsection[Using the Externalization Framework of PGF By Hand]
           {Using the Externalization Framework of {\normalfont\pgfname} ``By Hand''}

Another way to export \TeX{} pictures to single graphics files is to use the
externalization framework of \pgfname{}, which requires more work but works
more generally than the |external| library. The basic idea is to encapsulate
the desired parts with

\declareandlabel{\beginpgfgraphicnamed}\marg{output file name}

\meta{picture contents}

\declareandlabel{\endpgfgraphicnamed}.

\noindent Furthermore, one needs to tell \pgfname{} the name of the main
document using

\declareandlabel{\pgfrealjobname}\marg{the real job's name}

\noindent in the preamble. This enables two different modes:
%
\begin{enumerate}
    \item The first is the normal typesetting mode. \LaTeX{} checks whether a
        file named \meta{output file name} with one of the accepted file
        extensions exists -- if that is the case, the graphics file is
        included with |\pgfimage| and the \meta{picture contents} is skipped.
        If no such file exists, the \meta{picture contents} is typeset
        normally. This mode is applied if |\jobname| equals \meta{the real
        job's name}.
    \item The second mode applies if |\jobname| equals \meta{output file
        name}, it initiates the ``conversion mode'' which is used to write
        the graphics file \meta{output file name}. In this case, \emph{only}
        \meta{picture contents} is written to |\jobname|, the complete rest
        of the \LaTeX{} is processed as normal, but it is silently discarded.

        This mode needs to be started manually with
        |pdflatex --jobname |\meta{output file name} for every externalized
        graphics file.
\end{enumerate}
%
A complete example may look as follows.
%
\begin{codeexample}[code only]
\documentclass{article}
\usepackage{pgfplots}
    \pgfrealjobname{test}
\begin{document}
    \begin{figure}
        \beginpgfgraphicnamed{testfigure}
            \begin{tikzpicture}
                \begin{axis}
                    \addplot {x^2};
                \end{axis}
            \end{tikzpicture}
        \endpgfgraphicnamed
        \caption{Our first external graphics example}
    \end{figure}

    \begin{figure}
        \beginpgfgraphicnamed{testfigure2}
            \begin{tikzpicture}
                \begin{axis}
                    \addplot {x^3};
                \end{axis}
            \end{tikzpicture}
        \endpgfgraphicnamed
        \caption{A second graphics}
    \end{figure}
\end{document}
\end{codeexample}
%
\noindent The file is named |test.tex|, and it is processed (for example) with
%
\begin{codeexample}[code only]
pdflatex test
\end{codeexample}
%
\noindent Now, we type
%
\begin{codeexample}[code only]
pdflatex --jobname testfigure test
pdflatex --jobname testfigure2 test
\end{codeexample}
%
\noindent to enter conversion mode. These last calls will \emph{only} write the
contents of our named graphics environments, one for \meta{testfigure} and one
for \meta{testfigure2} into the respective output files |testfigure.pdf| and
|testfigure2.pdf|.

In summary, one needs |\pgfrealjobname| and calls
|pdflatex --jobname |\meta{graphics file} for every externalized graphics
environment. Please note that it is absolutely necessary to use the syntax
above, \emph{not} |\begin{pgfgraphicnamed}|.

These steps are explained in much more detail in Section``Externalizing
Graphics'' of~\cite{tikz}.


\paragraph{Attention:}

Do not forget a correct |\pgfrealjobname| statement! If it is missing,
externalization simply won't work. If it is wrong, any call to \LaTeX{} will
produce empty output files.

It should be noted that this approach of image externalization is not limited
to \Tikz{} picture environments. In fact, it collects everything between the
begin and end statements into the external file. It is implicitly assumed that
the encapsulated stuff is one box, but you can also encapsulate complete
paragraphs using something like the \LaTeX{} minipage (or a |\vbox| which is
not as powerful but does not affect the remaining document that much).

\begin{key}{/pgf/images/aux in dpth=\mchoice{true,false} (initially false)}
    If this boolean is set to |true|, any |\label| information generated inside
    of the external image is stored into the already mentioned |.dpth| file.
    The main document can thus reference label information of externalized
    parts of the document (although you may need to run |latex| several times).

    Label support is provided for |\ref|, and probably |\cite|. The |\pageref|
    command is only partially supported.
\end{key}


\paragraph{Using the Library Without {\normalfont\pgfname} Installed}

Simply uncomment the packages |\usepackage{tikz}| and |\usepackage{pgfplots}|
and use
%
\begin{codeexample}[code only]
\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{%
    \begingroup
    \setbox1=\hbox{\includegraphics{#1}}%
    \openin1=#1.dpth
    \ifeof1 \box1
    \else
        \read1 to\pgfincludeexternalgraphicsdp \closein1
        \dimen0=\pgfincludeexternalgraphicsdp\relax
        \hbox{\lower\dimen0 \box1 }%
    \fi
    \endgroup
}
\end{codeexample}
%
instead. This will include the generated graphics files (and it will respect
the |baseline| information stored in |.dpth| files). Consequently, you won't
need \pgfname{} or \PGFPlots{} installed. See Section``Externalizing Graphics''
of~\cite{tikz} for details.


\section{Importing From Matlab}

\subsection{Importing Mesh Data From Matlab To PGFPlots}
\label{sec:pgfplots:import:matlab}

While it is easy to write Matlab vectors to files (using
|save P.dat data -ASCII|), it is more involved to export mesh data.

The main problem is to communicate the mesh structure to \PGFPlots{}.

Here is an example how to realize this task: in Matlab, we have mesh data |X|,
|Y| and |Z| which are matrices of the same size. For example, suppose we have
%
\begin{codeexample}[code only]
[X,Y] = meshgrid( linspace(-1,1,5), linspace(4,5,10) );
Z = X + Y;
surf(X,Y,Z)
\end{codeexample}
%
\noindent as data. Then, we can generate an $N \times 3$ table containing all
single elements in column by column ordering with
%
\begin{codeexample}[code only]
data = [ X(:) Y(:) Z(:) ]
% or -ascii
save P.dat data -ASCII
size(X)
ans =
   10.00    5.00
\end{codeexample}
%
\noindent where the second command stores the $N \times 3$ table into |P.dat|.
Finally, we can use

|\addplot3[surf,mesh/rows=10,mesh/ordering=colwise,shader=interp] file {P.dat};|

in \PGFPlots{} to read this data. We need to provide either the number of rows
($10$ here) or the number of columns -- and the ordering (which is |colwise|
for Matlab matrices).

An alternative which is faster in \PGFPlots{} would be to transpose the
matrices in Matlab and tell \PGFPlots{} they are in |rowwise| ordering. So, the
last step becomes
%
\begin{codeexample}[code only]
XX=X'; YY=Y'; ZZ=Z';
data = [ XX(:) YY(:) ZZ(:) ]
save P.dat data -ASCII
\end{codeexample}
%
\noindent with \PGFPlots{} command

|\addplot3[surf,mesh/cols=10,mesh/ordering=rowwise,shader=interp] file {P.dat};|.


\subsection{matlab2pgfplots.m}

This is a Matlab$^\text{\textregistered}$ script which attempts to convert a
Matlab figure to \PGFPlots{}. It requires Matlab version 7.4 (or higher).


\paragraph{Attention:}

This script is largely outdated and supports only a very small subset of
\PGFPlots{}. You may want to look at |matlab2tikz|, a conversion script of Nico
Schlömer available at

\url{http://www.mathworks.com/matlabcentral/fileexchange/22022-matlab2tikz}

\noindent which also uses \PGFPlots{} for the \LaTeX{} conversion.

\medskip
The idea of |matlab2pgfplots.m| is to
%
\begin{itemize}
    \item use a complete Matlab figure as input,
    \item acquire axis labels, axis scaling (log or normal) and legend
        entries,
    \item acquire all plot coordinates
\end{itemize}
%
and write an equivalent \texttt{.pgf} file which typesets the plot with
\PGFPlots{}.

The intention is \emph{not} to simulate Matlab. It is a first step for a
conversion. Type
%
\begin{lstlisting}
> help matlab2pgfplots
\end{lstlisting}
%
on your Matlab prompt for more information about its features and its
limitations.

This script is experimental.


\subsection{matlab2pgfplots.sh}

A \texttt{bash}-script which simply starts Matlab and runs
%
\begin{lstlisting}
    f=hgload( 'somefigure.fig' );
    matlab2pgfplots( 'outputfile.pgf', 'fig', f );
\end{lstlisting}
%
See matlab2pgfplots.m above.


\subsection{Importing Colormaps From Matlab}

Occasionally, you may want to reuse your Matlab |colormap| in \PGFPlots{}. Here
is a small Matlab script which converts it to \PGFPlots{}:
%
\begin{codeexample}[code only]
C = colormap;  % gets data of the current colormap.
% C = colormap(jet) % gets data of "jet"
eachnth = 1;
I = 1:eachnth:size(C,1); % this is nonsense for eachnth=1 -- but perhaps you don't want each color.
CC = C(I,:);
TeXstring = [ ...
 sprintf('\\pgfplotsset{\n\tcolormap={matlab}{\n') ...
 sprintf('\t\trgb=(%f,%f,%f)\n',CC') ...
 sprintf('\t}\n}\n') ]
\end{codeexample}


\section{SVG Output}

It is possible to write every single \Tikz{} picture into a scalable vector
graphics (\texttt{.svg}) file. This has nothing to do with \PGFPlots{}, it is a
separate driver of \PGF{}. Please refer to~\cite[Section ``Producing HTML / SVG
Output'']{tikz}.


\section{Generate \PGFPlots{} Graphics Within Python}

Mario Orne DÍAZ ANADÓN contributed a small python script |pgfplots.py| which
provides a simple interface to generate \PGFPlots{} figures from within python.
It can be found in the \PGFPlots{} installation directory, in
|pgfplots/scripts/pgfplots/pgfplots.py|; documentation can be found in the
file.

}
